Update race docs for new 3.5 semantics#4526
Open
valencik wants to merge 1 commit intotypelevel:series/3.xfrom
Open
Update race docs for new 3.5 semantics#4526valencik wants to merge 1 commit intotypelevel:series/3.xfrom
race docs for new 3.5 semantics#4526valencik wants to merge 1 commit intotypelevel:series/3.xfrom
Conversation
durban
reviewed
Nov 23, 2025
| /** | ||
| * Races the evaluation of two fibers that returns the result of the winner, except in the | ||
| * case of cancelation. | ||
| * case of cancelation which cancels the whole race. |
Contributor
There was a problem hiding this comment.
I think this is ambiguous: "in the case of cancelation" <- what does this mean? If the fiber executing race is canceled? If one or the other side cancels?
| * masked and is canceled because both participants canceled, the fiber will block | ||
| * indefinitely. | ||
| * returning. 3. If the winner completes with [[Outcome.Canceled]], the loser is canceled | ||
| * immediately but its outcome is returned if already completed. 4. If the race is masked |
Contributor
There was a problem hiding this comment.
There is a subtle point here: if the loser is cancelled, its Succeeded result can be returned even if it's yet to happen.
In other words: "the loser is canceled immediately but its outcome is returned if already completed" <- I think this sentence suggests, that if the loser is not yet completed when it's cancelled, then its outcome will not be returned. This is not true.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
I am attempting to clarify the documentation for
raceafter the semantic change in 3.5.0, introduced in #3453Namely, the following is now incorrect:
Nailing down this language is tricky.
With less rigidity, here's my understanding of the current behaviour:
If winner
Succeededwe cancel loser and return winning value!If winner
Erroredwe cancel loser and raise the error.If the winner is
Canceled, most of the time we are going to getCanceledoverall. The exception is if the loser has managed to also complete, at which point, we already have the loser's value, so why not dish it out.In other words, Loser is always getting canceled, but if completed prior to that cancelation, we'll let it share its results with the world.
I admit I don't really grok the importance of rule 4 here:
Is this a detail that users need in this documentation? I honestly don't know